Release 10.1A: OpenEdge Development:
Web Services

Defining header handlers

A 4GL application does most of the work for accessing or creating a SOAP header in the two header handlers that you can invoke for Web service operations ( Chapter 10 "Invoking Web Service Operations from the Progress 4GL"). These include a callback procedure for handling the SOAP response message header and another callback procedure for handling the SOAP request message header for the operation. This is the syntax for defining the signatures for these two procedures:

SOAP response header callback procedure:

Syntax

PROCEDURE response-header-procname :   DEFINE INPUT PARAMETER hSOAPHeader AS HANDLE .   DEFINE INPUT PARAMETER cOperationNamespace AS CHARACTER .   DEFINE INPUT PARAMETER cOperationLocalName AS CHARACTER . END PROCEDURE .

SOAP request header callback procedure:

Syntax

PROCEDURE request-header-procname :   DEFINE OUTPUT PARAMETER hSOAPHeader AS HANDLE .   DEFINE INPUT  PARAMETER cOperationNamespace AS CHARACTER .   DEFINE INPUT  PARAMETER cOperationLocalName AS CHARACTER .   DEFINE OUTPUT PARAMETER lDeleteOnDone AS LOGICAL . END PROCEDURE .

These are the parameters:

response-header-procname — The name of a response header handler procedure. Specified as a character expression to the SET-CALLBACK-PROCEDURE( ) method along with the "RESPONSE-CALLBACK" setting.
request-header-procname — The name of a request header handler procedure. Specified as a character expression to the SET-CALLBACK-PROCEDURE( ) method along with the "REQUEST-CALLBACK" setting.
hSOAPHeader — A handle to a SOAP header object that encapsulates the header of the SOAP message that is about to be sent (request header) or that has just been received (response header). In a response header handler, the SOAP header object has no content if the NUM-HEADER-ENTRIES attribute on the object handle returns the value 0; otherwise it contains one or more SOAP header entries. In a request header handler, this is an OUTPUT parameter, therefore if the outgoing SOAP message requires a SOAP header, you must either build a SOAP header for this parameter to reference or provide an existing SOAP header saved from a previous response callback.
cOperationNamespace — Contains the namespace portion of the operation’s qualified name. Use this parameter together with the cOperationLocalName parameter if you need to identify the operation for which the SOAP message is being sent or received.
cOperationLocalName — Contains the local-name portion of the operation's qualified name. Use this parameter together with the cOperationNamespace parameter if you need to identify the operation for which the SOAP message is being sent or received.
lDeleteOnDone — (Request callback only) Tells OpenEdge to delete the SOAP header object and all of the parsed XML after the SOAP header has been inserted into the out-bound SOAP message. For more information on the scope of these objects, see the "Managing memory for SOAP headers" section.

For both types of callback procedure you can use the INPUT parameters, cOperationNamespace and cOperationLocalName, to determine the Web service operation for which the message is generated. You might use this information either to determine how to parse the SOAP response header based on the invoked operation or to build a SOAP request header that is specific to the invoked operation.

If you need to pass context between the code that invokes a Web service operation and a header callback procedure, you can pass the context information as you might for any internal procedure:

Use procedure variables global to the calling code, if the callback procedure is defined within the context of the calling code.
Use the PRIVATE-DATA attribute on the procedure context handle (THIS-PROCEDURE) of the header handler.